home *** CD-ROM | disk | FTP | other *** search
/ World of Amiga / World of Amiga.iso / archive / 3d / real_developer.lha / document < prev    next >
Text File  |  1992-07-22  |  15KB  |  414 lines
  1.  
  2. INTERFACE FROM REAL 3D TO CUSTOM DISPLAY DEVICES
  3. ------------------------------------------------
  4.  
  5. Contents
  6. --------
  7.  
  8. General notes
  9. The user interface for the custom display
  10. The library interface for the custom display
  11. Creating the interface library
  12.  
  13.  
  14. General notes
  15. -------------
  16.  
  17. It is possible to connect a custom display device (frame buffer etc.)
  18. to Real 3D so that images can be rendered directly to the custom display. 
  19. This kind of direct support can be obtained by creating a simple shared 
  20. library containing some elementary functions.
  21.  
  22.  
  23.  
  24. The user interface for the custom display
  25. -----------------------------------------
  26.  
  27. The custom display is controlled using a set of menu functions in the 
  28. Real 3D's Rendering Control Screen. These menu functions are:
  29.  
  30.  
  31. Library name 
  32. This function allows the user to define the name of the desired shared 
  33. library. This information is saved to R3D's configuration file when the 
  34. user exits the program.
  35.  
  36. Open screen
  37. Tries to obtain access to the custom display. If opening is successful,
  38. 24 bit rendering is directed to the custom display. The function also
  39. sets default resolution and display modes.
  40.  
  41. Close screen
  42. Frees the custom display. For example, if the access is exclusive (no 
  43. multiple screens supported), other multitasking programs can access the 
  44. display after this.
  45.  
  46. Set modes
  47. Allows the user to select desired custom display modes, such as interlace, 
  48. hires, resolution etc. All the options available in the function depend on
  49. the device used. 
  50.  
  51. 24 bit save 
  52. This function saves the custom display image by reading the image line by
  53. line and saving it using R3D's own Targa/IFF ILBM saving routines.
  54.  
  55. Custom save
  56. This function can be used to save the custom display image in its native
  57. format instead of the standard 24 bit formats. For example, if the custom
  58. display is not a true 24 bit display, there are probably more memory 
  59. efficient ways to save the image. Also, the function can be used for 
  60. faster image saving, because line based data transfer in the standard 
  61. 24 bit save function inevitably requires extra data moving and format
  62. transformations, and is consiquently somewhat slow. Nevertheless, a proper 
  63. implementation of this function is optional; the library may contain a 
  64. non-operational function instead.
  65.  
  66.  
  67. In addition to the previous functions, most of the other rendering 
  68. controls (Prefs->Aspect ratio, image size etc.) affect the custom display.
  69.  
  70.  
  71. An example of custom display usage from Real 3D:
  72.  
  73. - Install the custom display hardware and its driver software to your 
  74. system. 
  75.  
  76. - Copy the R3D-custom display interface library to LIBS: directory.
  77. The name of this library is usually of the form xxx_r3d.library.
  78.  
  79. - Activate Real 3D, create a scene and go to solid model by selecting
  80. Modes->Solid. Select Lampless, Shadowless or Normal rendering mode and 
  81. activate either Targa or IFF 24 option (these selections are automatically
  82. made if you Projects->Animation->Load the test scene 'TestScene' included 
  83. in the disk).
  84.  
  85. - Select the rightmost menu 'Frame buffer' of the rendering 
  86. control screen and the first function 'Library name' of it. Then type
  87. the name of of the interface library and select OK.
  88.  
  89. - If the hardware is successfully installed and the library name string is
  90. correct, the frame buffer menu contains now all the functions listed above.
  91.  
  92. - Select Frame buffer->Open screen. If the opening was successfull, the 
  93. resolution fields are updated to show the custom display dimensions.
  94.  
  95. - You may now try to change the custom display resolution and other such 
  96. properties using the Frame buffer->Set modes function. 
  97.  
  98. - Click Render button. The image should start to appear to the custom 
  99. display. If not, the rendering is probably directed to a hard disk file,
  100. which can be detected from increased hard disk activity; if this occurs,
  101. repeat the previous steps to ensure proper installation and usage.
  102. You can cancel the rendering by clicking the render button again.
  103.  
  104. - When the image is ready, you can save it by selecting Frame buffer->
  105. 24 bit save. This asks the name for the image and saves the image in 24 bit
  106. Targa/IFF format, depending on the option selected when rendering the image.
  107. You may also try to save the image using the Custom save function, but
  108. it is possible that the function is not operational. Nevertheless, it is
  109. harmless to try it.
  110.  
  111. - When you do not need the custom display any longer, close it using the
  112. Frame buffer->Close screen menu (of course, the screen is automatically
  113. closed when the user exits the program).
  114.  
  115. - For further details of the Custom save format and the features included
  116. in the Set modes functions, read the readme file of the interface library 
  117. of your custom display device. This file should contain all the hardware
  118. specific details.
  119.  
  120.  
  121.  
  122. The library interface for the custom display
  123. --------------------------------------------
  124.  
  125. The shared library needed to connect a display hardware product to Real 3D
  126. must contain the following functions:
  127.  
  128. R3DInitDspDrv()
  129. R3DFreeDspDrv(handle)
  130. R3DSetMode(handle)
  131. R3DGetSize(handle,x,y)
  132. R3DWriteLine(handle,buffer,len,x,y)
  133. R3DReadLine(handle,buffer,len,x,y)
  134. R3DClsScr(handle,col)
  135. R3DCustomSave(handle,name,x,y,w,h)
  136.  
  137.  
  138. Function descriptions:
  139.  
  140. All the integers in the following descriptions are 32 bit wide.
  141.  
  142.  
  143. *** NAME 
  144.         R3DInitDspDrv -- allocate and initialize a screen on the custom
  145.         display
  146.        
  147.     SYNOPSIS
  148.         int R3DInitDspDrv()
  149.        
  150.     FUNCTION
  151.         Allocates and initialises a custom display and sets default
  152.         display formats. The screen may or may not be cleared when opened;
  153.         it is cleared whenever rendering starts, anyway.
  154.  
  155.         The main purpose of this function is to get access to the custom 
  156.         display. After the call, the custom display should be ready to
  157.         receive and send data, to be cleared and to other such manipulations
  158.         needed when rendering images to the custom display.
  159.  
  160.         For example, this function may open the actual library for the
  161.         display device and then open a screen.
  162.     
  163.         After the function, Real 3D asks the resolution for the custom 
  164.         display using the R3DGetSize() function and resets image size 
  165.         to this resolution.
  166.  
  167.     INPUTS
  168.  
  169.     RESULT
  170.         A non-zero value, if the call was successfull. The value is used
  171.         as a handle, with which the custom display is accessed. Real 3D 
  172.         does not utilize multiple custom display screens yet, but this 
  173.         may change in the future versions. 
  174.    
  175.     SEE ALSO
  176.         R3DFreeDspDrv(), R3DSetMode(), R3DGetSize() 
  177.  
  178.     
  179. *** NAME 
  180.         R3DFreeDspDrv -- closes a custom display previously opened 
  181.         by a call to R3DInitDspDrv
  182.  
  183.     SYNOPSIS
  184.         void R3DInitDspDrv(int handle)
  185.                             A0
  186.  
  187.     FUNCTION
  188.         Frees the custom display access. For example, it may close a
  189.         screen and then close the actual library for the display device.
  190.  
  191.     INPUTS
  192.         handle -- a handle obtained by a call to R3DInitDspDrv
  193.  
  194.     RESULT
  195.    
  196.     SEE ALSO
  197.         R3DInitDspDrv()
  198.  
  199.  
  200. *** NAME 
  201.         R3DSetMode -- Asks and sets display modes, resolution etc. 
  202.         properties for the custom display
  203.  
  204.     SYNOPSIS
  205.         void R3DSetMode(int handle)
  206.                          A0
  207.  
  208.     FUNCTION
  209.         This function is used to select hardware specific options for
  210.         the custom display device. It should request all the relevant 
  211.         options available for the device such as INTERLACE, PAL/NTSC, 
  212.         full screen resolution alternatives, display depth etc. 
  213.     
  214.         The mode request may be done for example by opening a requester 
  215.         on the IntuitionBase->ActiveWindow and by monitoring the UserPort
  216.         of this window. Real 3D's rendering control screen window is 
  217.         guaranteed to contain GADGETUP class IDCMP messages. Nevertheless,
  218.         any other screen or method may be used as well. Also, the function 
  219.         may be non-operational, if only one display mode and size is 
  220.         available.
  221.  
  222.         After getting the mode selections from the user, the custom display
  223.         defined by handle should be modified to fulfill the selections;
  224.     the current image may be cleared, trashed or preserved. After the 
  225.     function, Real 3D asks the new full screen resolution 
  226.         using the R3DGetSize() function. 
  227.  
  228.     INPUTS
  229.         handle -- a handle obtained by a call to R3DInitDspDrv
  230.  
  231.     RESULT
  232.    
  233.     SEE ALSO
  234.         R3DGetSize()
  235.  
  236.  
  237. *** NAME 
  238.         R3DGetSize -- Asks the current full screen resolution of the 
  239.         custom display
  240.  
  241.     SYNOPSIS
  242.         void R3DGetSize(int handle,int *x,int *y)
  243.                          A0         A1     D0
  244.  
  245.     FUNCTION
  246.         This function is used to find out the full screen resolution 
  247.         of the custom display after opening it and after mode selections.
  248.  
  249.     INPUTS
  250.         handle -- a handle obtained by a call to R3DInitDspDrv
  251.         x      -- a pointer to 32 bit integer to which the horizontal 
  252.                   resolution is written
  253.         y      -- a pointer to 32 bit integer to which the vertical
  254.                   resolution is written
  255.  
  256.     RESULT
  257.    
  258.     SEE ALSO
  259.         R3DSetMode()
  260.  
  261.  
  262. *** NAME 
  263.         R3DWriteLine -- Writes a line of rgba data into the custom display
  264.  
  265.     SYNOPSIS
  266.         void R3DWriteLine(int handle,int *buffer,int len,int x,int y)
  267.                            A0         A1          A2      D0    D1
  268.  
  269.     FUNCTION
  270.         This function writes one line of data, pointed by the parameter
  271.         buffer, into the custom display. The data is in the form 
  272.         rgba rgba ..., four consecutive bytes for each pixel. The fourth
  273.         byte 'a' is for alpha channel; this is not utilized by the current
  274.         Real 3D version, but this may change in the future versions. The
  275.         values for each color channel have range 0-255.
  276.  
  277.         The position of the target line on the custom display is defined 
  278.         by the offset parameters x and y, and the length of the line is 
  279.         defined by the parameter len. 
  280.  
  281.     INPUTS
  282.         handle -- a handle obtained by a call to R3DInitDspDrv
  283.         buffer -- points to 4*len bytes of rgba data to be written
  284.         len    -- the number of pixels to be written
  285.         x, y   -- offset values from the top left corner
  286.  
  287.     RESULT
  288.    
  289.     SEE ALSO
  290.         R3DReadLine()
  291.  
  292.  
  293. *** NAME 
  294.         R3DReadLine -- Reads a line of rgba data from the custom display
  295.         to a buffer
  296.  
  297.     SYNOPSIS
  298.         void R3DReadLine(int handle,int *buffer,int len,int x,int y)
  299.                           A0         A1          A2      D0    D1
  300.  
  301.     FUNCTION
  302.         This function reads the color of len pixels into buffer. The data
  303.         is written in the form rgba rgba ..., four consecutive bytes for 
  304.         each pixel. The fourth byte 'a' is for alpha channel; this is not 
  305.         utilized by the current Real 3D version, but this may change in the
  306.         future versions. The values for each color channel should be scaled
  307.         to full range 0-255.
  308.  
  309.         The data is read starting from the position (x,y), and the length 
  310.         of the line is defined by the parameter len. 
  311.  
  312.     INPUTS
  313.         handle -- a handle obtained by a call to R3DInitDspDrv
  314.         buffer -- points to 4*len bytes of buffer area
  315.         len    -- the number of pixels to be read
  316.         x, y   -- offset values from the top left corner
  317.  
  318.     RESULT
  319.    
  320.     SEE ALSO
  321.         R3DWriteLine()
  322.  
  323.  
  324. *** NAME 
  325.         R3DClsScr -- Clears the custom display
  326.  
  327.     SYNOPSIS
  328.         void R3DClsScr(int handle, int color)
  329.                         A0          A1
  330.  
  331.     FUNCTION
  332.         This function clears the color of the custom display to a specified
  333.         color.  The color is defined by the parameter 'color' in the form
  334.         rgba, one byte for each color channel. 
  335.         
  336.         This function is always called when starting to render an image,
  337.         and therefore it can be used for other device dependent preparations,
  338.         too. After the call, the custom display should be ready to receive
  339.         consecutive R3DWriteLine() data lines.
  340.  
  341.     INPUTS
  342.         handle -- a handle obtained by a call to R3DInitDspDrv
  343.         color  -- the background color of the display after the call 
  344.  
  345.     RESULT
  346.    
  347.     SEE ALSO
  348.         R3DWriteLine()
  349.  
  350.  
  351. *** NAME 
  352.         R3DCustomSave -- Saves the custom display image
  353.  
  354.     SYNOPSIS
  355.         void R3DCustomSave(int handle,char *name,int x,int y,int w,int h)
  356.                             A0         A1         A2    D0    D1    D2
  357.  
  358.     FUNCTION
  359.         This function may be used to save a part of the custom display 
  360.         contents. The functionality of R3DCustomSave() is optional, 
  361.         because standard 24 bit saving facilities of Real 3D are 
  362.         available.
  363.         
  364.         There are two reasons to implement the function: first of all,
  365.         the speed, and secondly, custom formats. There are several display
  366.         devices available, whose picture information can be stored more
  367.         efficiently than when using 24 bit formats.
  368.  
  369.     INPUTS
  370.         handle -- a handle obtained by a call to R3DInitDspDrv
  371.         name   -- null-terminated character string for the image file name 
  372.         x,y    -- the top-left corner of the sub-image to be saved
  373.         w,h    -- the size of the sub-image to be saved
  374.  
  375.     RESULT
  376.    
  377.     SEE ALSO
  378.         
  379.  
  380.  
  381. Creating the interface library for Real 3D
  382. ------------------------------------------
  383.  
  384. The functions of the previous chapter may be implemented quite freely.
  385. For example, there are no special requirements for mode query, custom 
  386. saving, multiple screens or alpha channel usage. 
  387.  
  388. The library may be created quite easily by modifying the example code 
  389. contained in this disk; the rather primitive but sufficient example is 
  390. for interfacing ACS Harlequin frame buffer.
  391.  
  392. We have used 'xxx_r3d.library' naming convention for interface 
  393. libraries, but this is optional.
  394.  
  395. The interface library should be documented with a text file, which
  396. describes the user-visible features of the library, that is, the options 
  397. available in the Set modes function and the Custom save function.
  398.  
  399. If the function collection documented here seems not to be sufficient,
  400. please inform Realsoft of the new functions required, so that they can be 
  401. added to the end of the library, and relevant calls can be added into 
  402. the program itself. Also, if this document contains insufficient amount
  403. of information for creating the library, please do not hesitate contact me:
  404.  
  405.     Realsoft KY
  406.     Attn. Vesa Meskanen
  407.     KP 9, SF-35700 Vilppula
  408.     Finland
  409.  
  410.     tel./fax +358-34-48390 
  411.  
  412.  
  413.  
  414.